PUT /manage/v2/forests/{id|name}/properties

Summary

Modify the configuration of the forest identified by {id|name}.

Response

Upon success, MarkLogic Server returns a status code 204 (No Content).

Required Privileges

• the manage-admin role
• the following privilege:

  http://marklogic.com/xdmp/privileges/manage

  http://marklogic.com/xdmp/privileges/admin/forest

• the manage role plus one of the following granular privileges:
  • http://marklogic.com/xdmp/privileges/admin/forest
  • http://marklogic.com/xdmp/privileges/admin/forest/forest-ID

Usage Notes

Properties included in the payload replace the existing configuration of the same property, if any. All other properties remain unchanged. Replacement applies even where multiple property values are supported, such as replica forests. For example, if the request includes configuration for forest-replicas, all previously existing replica configuration is replaced. The operation is not additive.

Note: The properties described here are for XML payloads. In general they are the same for JSON, with the exception that, in JSON, failover-hosts and forest-replicas are expressed in singular form. For example, in JSON, failover-hosts is instead failover-host and the format is: "failover-host":["hostname"].

Note that adding or removing a replica forest to/from a master forest will take the master forest offline.

The structure of the modifiable properties is as follows:

The following properties are immutable: database, host, data-directory, large-data-directory, and fast-data-directory.

If database replication is configured such that the connect-forests-by-name property is false, then forest-level replication can be changed with the database-replication properties of the forests. Specify foreign replicas on the replica forests and foreign-master on the master forest.

database

The name of the database to which this forest is attached.

forest-name

The forest name.

enabled

Forest enabled status.

host

The primary host to which the forest is assigned.

data-directory

The optional public directory for forests.

large-data-directory

The optional directory for large objects in a forest.

fast-data-directory

The optional smaller but faster directory for forests.

fast-data-max-size

Maximum allowable size (in megabytes) of the data to be kept by this forest in the fast-data-directory, or 0 for no limit.

updates-allowed

The kinds of updates that should be allowed for this forest.

availability

Availability of the forest data.

rebalancer-enable

Enable automatic rebalancing after configuration changes.

range

Range configuration for the range assignment policy.

This is a complex structure with the following children:

lower-bound

The lower bound of the range on the forest.

upper-bound

The upper bound of the range on the forest.

partition-number

A partition number for query assignment policy

failover-enable

Enable assignment to a failover host if the primary host is down.

failover-hosts

A list of failover hosts for shared-disk failover.

This is a complex structure with the following children:

failover-host

A failover host.

forest-backups

Backups scheduled for this forest.

This is a complex structure with the following children:

forest-backup

A scheduled forest backup.

This is a complex structure with the following children:

backup-id

The backup ID.

backup-enabled

Whether or not a backup is enabled

backup-directory

The backup directory pathname.

backup-type

What type of backup is this.

backup-period

How often this backup should run (every n months, weeks, days, hours or minutes).

backup-month-day

The day of the month that this backup happens.

backup-days

The days that this backup happens.

This is a complex structure with the following children:

backup-day

A day that this backup occurs.

backup-start-date

The starting date (in MM/DD/YYYY notation) for a one-time backup

backup-start-time

The starting time (in 24:00 notation).

backup-timestamp

The date and time this backup was created.

forest-replicas

A list of replica forests, used for local-disk failover (changes will reboot the primary forest).*

This is a complex structure with the following children:

forest-replica

The unique key of a forest.

This is a complex structure with the following children:

host

The primary host to which the forest is assigned.

replica-name

The name of a replica forest

data-directory

The optional public directory for forests.

large-data-directory

The optional directory for large objects in a forest.

fast-data-directory

The optional smaller but faster directory for forests.

database-replication

Database replication configuration.

This is a complex structure with the following children:

foreign-replicas

Foreign replicas of this database.

This is a complex structure with the following children:

foreign-replica

Foreign replica of this database.

This is a complex structure with the following children:

foreign-cluster-name

A foreign cluster ID.

foreign-database-name

A foreign database ID.

foreign-forest-name

A foreign forest ID.

foreign-master

Foreign replica of this database.

This is a complex structure with the following children:

foreign-cluster-name

A foreign cluster ID.

foreign-database-name

A foreign database ID.

foreign-forest-name

A foreign forest ID.

Example

$ cat ./forest-properties.xml
==> 
<forest-properties xmlns="http://marklogic.com/manage">
  <enabled>false</enabled>
</forest-properties>

$ cat ./forest-properties.json
==> 
{ "enabled": true }

$ curl --anyauth --user user:password -X PUT -d @./forest-properties.xml \
    -i -H "Content-type: application/xml" \
    http://localhost:8002/manage/v2/forests/example-1/properties

==> The enabled property of the forest named example-1 is set to false.
    All other properties are unchanged. MarkLogic Server responds with
    output similar to the following:

HTTP/1.1 204 No Content
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5